It has been designed so that for SwaggerUi::new(...) and .url(...) and .urls(...) the path provided should be relative path from the root of the server.

So why just not like this?

SwaggerUi::new("/v1/swagger/*tail")
    .url("/v1/openapi.json", openapi);

Also in a same way the you could have only SwaggerUi have the path /swagger/*tail and url to have /v1/openapi.json

SwaggerUi::new("/swagger/*tail")
    .url("/v1/openapi.json", openapi);

It originally was not designed so that someone would define the paths separately with additional config thus it just overrides the config urls with the SwaggerUi urls. We could add this support though as well but this should be also added to the actix.rs and rocket.rs since they have the same behaviour as the axum.rs has.

I think this issue is caused by axum's nest method.

My application is like below.

let swagger = SwaggerUi::new("/swagger/*tail")
        .url("/openapi", openapi);

let services = Router::new()
        .route("/", get(root))
        .route("/users", get(list_users))
        .merge(swagger);

let app = Router::new()
        .nest("/v1", services)  // This makes all endpoints start from "/v1" prefix
        .layer(Extension(db_connection_pool));

let addr = SocketAddr::from(([0, 0, 0, 0], 3000));
axum::Server::bind(&addr)
    .serve(app.into_make_service())
    .await
    .unwrap();

Because of nest, in the above code SwaggerUI is served in /v1/swagger and OpenAPI JSON is served /v1/openapi.
But SwaggerUIBundle reads /openapi to fetch JSON.

If you set SwaggerUi::new("/swagger/*tail").url("/v1/openapi", openapi) on SwaggerUI struct (this is your idea), then SwaggerUI is served in /v1/swagger and OpenAPI JSON is served in /v1/v1/openapi.
In this case SwaggerUIBundle reads /v1/openapi correctly.

Like this, I feel it's better to split url config between router and SwaggerUIBundle config.

Of course, I can achieve this design by merging swagger route with avoiding nest method, like this.

Router::new()
    .nest("/v1", services)
    .merge(swagger)

Maybe this issue can be resolved by describing this specification in docs without changing utoipa's codes.

If you set SwaggerUi::new("/swagger/*tail").url("/v1/openapi", openapi) on SwaggerUI struct (this is your idea), then SwaggerUI is served in /v1/swagger and OpenAPI JSON is served in /v1/v1/openapi.
In this case SwaggerUIBundle reads /v1/openapi correctly.

Oh yeah, true it does not work since the SwaggerUi writes the given urls to the swagger-ui bundle as well which is not aware of the nest function.

Of course, I can achieve this design by merging swagger route with avoiding nest method, like this.

Router::new()
   .nest("/v1", services)
   .merge(swagger)

Maybe this issue can be resolved by describing this specification in docs without changing utoipa's codes.

This looks to me quite elegant solution, and if it works it could be mentioned in docs. There also could be an example in examples folder as well regarding this.

I'm not opposing the change, it's just that I feel like there is some room for an improvement on how users define the url and openapi mapping. If there are multiple definitions of single url it's hard to tell which one should be the authoritative one.

@komi1230 I was thinking about this change and it is reasonable to make. So after next release you also split the configuration as you originally intented. 🙂

Like this, I feel it's better to split url config between router and SwaggerUIBundle config.

I agree, I continue on this branch to make this change for other frameworks as well.